Replace CI/Zuul references with manual commands in HSM adoption docs by mauricioharley · Pull Request #1392 · openstack-k8s-operators/data-plane-adoption

mauricioharley · 2026-05-13T14:41:06Z

Problem

The Key Manager (Barbican) HSM adoption documentation contained references to CI-specific tooling (Zuul job vars, CI framework configuration, cifmw_* variables) that are not applicable to users performing adoption manually. This made the Proteccio HSM procedure (section 4.4.2) impossible to follow as a user.

Replace CI-oriented instructions with concrete manual commands (oc create secret, oc patch) following the same pattern used by the simple_crypto adoption procedure (section 4.3). Update related concept modules and troubleshooting procedures to remove CI references and use user-facing terminology throughout.

Solution

Rewrite the Proteccio HSM procedure (section 4.4.2) to follow the same manual approach used by the simple_crypto adoption procedure (section 4.3): explicit oc create secret and oc patch openstackcontrolplane commands with documented replaceable parameters.

klgill · 2026-05-15T12:38:05Z

-* Uses the enhanced `barbican_adoption` role with HSM awareness
-* Configures HSM integration through a simple boolean flag (`barbican_hsm_enabled: true`)
-* Automatically creates required Kubernetes secrets (`hsm-login` and `proteccio-data`)
+* Patches the `OpenStackControlPlane` CR with HSM-enabled configuration


Suggested change

* Patches the `OpenStackControlPlane` CR with HSM-enabled configuration

* Patches the `OpenStackControlPlane` custom resource with HSM-enabled configuration

klgill · 2026-05-15T12:38:52Z

 * Supports both simple crypto and HSM back ends in the target environment
-* Requires HSM-specific configuration variables and custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)
-* Uses HSM client certificates and configuration files accessible via URLs
+* Requires custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)


Suggested change

* Requires custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)

* Requires custom container images with HSM client libraries that are built by using the `rhoso_proteccio_hsm` Ansible role

klgill · 2026-05-15T12:50:47Z

@@ -21,4 +21,4 @@ The {key_manager} supports HSM integration through the PKCS#11 plugin. This enab
 * Compliance with security requirements for production environments
 * Preservation of existing HSM-protected secrets during adoption



@mauricioharley This module is not currently included in the adoption guide. If there is value in including this, we should add it to the "assembly_rhoso-180-adoption-overview.adoc" assembly.

Hi, @klgill. This module was already present in the repository before this PR. We only changed the xref anchor to match the corrected procedure ID. Including it in assembly_rhoso-180-adoption-overview.adoc is a separate concern. Happy to add it in a follow-up PR if you think it adds value.

klgill · 2026-05-15T12:52:09Z

 * Preservation of existing HSM-protected secrets during adoption

-HSM integration is configured through a simple boolean flag (`barbican_hsm_enabled`) during the adoption process. For environments that require HSM integration during adoption, see xref:adopting-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].
+For environments that require HSM integration during adoption, see xref:adopting-the-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].


Suggested change

For environments that require HSM integration during adoption, see xref:adopting-the-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].

For environments that require HSM integration during adoption, see xref:adopting-the-key-manager-service-with-proteccio-hsm_hsm-integration[Adopting the {key_manager} with Proteccio HSM integration].

klgill · 2026-05-15T12:54:42Z

 ----

-. If you are not using the automated adoption, create HSM-specific secrets in the target environment:
+. Create HSM-specific secrets in the target environment:


Does "target environment" refer to RHOSO? If so, we could be more specific and use the {rhos_acro} attribute (renders as "RHOSO").

Good call. Updated to {rhos_acro} target environment in the latest push.

klgill · 2026-05-15T13:08:18Z


-Without proper HSM configuration, your HSM-protected secrets become inaccessible after adoption.
+* The HSM partition name, MKEK label, and HMAC label match the values configured in your source environment.
+* The Proteccio client certificates and configuration files are valid for the target environment.


You could add "...source environment (RHOSP)" and "...target environment (RHOSO)" to be more explicit.

Agreed. Updated to include ({OpenStackShort}) and ({rhos_acro}) explicitly in the latest push.

klgill · 2026-05-15T13:09:57Z

-# Enable HSM integration for the Barbican adoption role
-barbican_hsm_enabled: true
+
+If you see the `[p11_crypto_plugin]` section with Proteccio-specific settings, for example `library_path = /usr/lib64/libnethsm.so`, continue with the HSM adoption.


What if the customer doesn't see the settings?

Added guidance directing the user to the standard adoption procedure if the [p11_crypto_plugin] section is not found.

klgill · 2026-05-15T13:13:35Z

+`<path_to_client_key>`::
+Specifies the path to the HSM client key file.
+`<hsm_server_cert_filename>`::
+Specifies the filename of the HSM server certificate as expected by the Proteccio client, for example, `10_8_60_93.CRT`.


Suggested change

Specifies the filename of the HSM server certificate as expected by the Proteccio client, for example, `10_8_60_93.CRT`.

Specifies the filename of the HSM server certificate that is expected by the Proteccio client, for example, `10_8_60_93.CRT`.

klgill · 2026-05-15T13:28:16Z

 .Procedure

-. Edit your hardware security module configuration in the Zuul job vars or CI framework configuration file.
+. Check the `OpenStackControlPlane` CR patch and the Kubernetes secrets that you created during the adoption procedure.


Suggested change

. Check the `OpenStackControlPlane` CR patch and the Kubernetes secrets that you created during the adoption procedure.

. Check the `OpenStackControlPlane` custom resource (CR) patch and the Kubernetes secrets that you created during the adoption procedure.

klgill · 2026-05-15T13:42:03Z

-    "msg": "No HSM configuration found - using standard adoption"
-}
----
+If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` CR includes the correct HSM settings.


Suggested change

If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` CR includes the correct HSM settings.

If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` custom resource (CR) includes the correct HSM settings.

The Key Manager (Barbican) HSM adoption documentation contained references to CI-specific tooling (Zuul job vars, CI framework configuration, cifmw_* variables) that are not applicable to users performing adoption manually. This made the Proteccio HSM procedure (section 4.4.2) impossible to follow as a user. Replace CI-oriented instructions with concrete manual commands (oc create secret, oc patch) following the same pattern used by the simple_crypto adoption procedure (section 4.3). Update related concept modules and troubleshooting procedures to remove CI references and use user-facing terminology throughout. Signed-off-by: Mauricio Harley <mharley@redhat.com>

klgill

/lgtm

jistr · 2026-05-19T07:49:43Z

/lgtm
/approve

openshift-ci · 2026-05-19T07:49:50Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jistr

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [jistr]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

mauricioharley requested a review from klgill May 15, 2026 09:53

mauricioharley self-assigned this May 15, 2026

klgill requested changes May 15, 2026

View reviewed changes

mauricioharley force-pushed the fix/remove-ci-references-from-hsm-docs branch from 36fc900 to 917ecc9 Compare May 18, 2026 16:04

mauricioharley requested a review from klgill May 18, 2026 16:12

klgill approved these changes May 18, 2026

View reviewed changes

openshift-ci Bot assigned klgill May 18, 2026

openshift-ci Bot added the lgtm label May 18, 2026

openshift-ci Bot assigned jistr May 19, 2026

openshift-ci Bot added the approved label May 19, 2026

openshift-merge-bot Bot merged commit 5fb8c08 into openstack-k8s-operators:main May 19, 2026
6 checks passed

	* Patches the `OpenStackControlPlane` CR with HSM-enabled configuration
	* Patches the `OpenStackControlPlane` custom resource with HSM-enabled configuration

	* Requires custom container images with HSM client libraries (built using the `rhoso_proteccio_hsm` Ansible role)
	* Requires custom container images with HSM client libraries that are built by using the `rhoso_proteccio_hsm` Ansible role

		@@ -21,4 +21,4 @@ The {key_manager} supports HSM integration through the PKCS#11 plugin. This enab
		* Compliance with security requirements for production environments
		* Preservation of existing HSM-protected secrets during adoption

	For environments that require HSM integration during adoption, see xref:adopting-the-key-manager-service-with-proteccio-hsm_{context}[Adopting the {key_manager} with Proteccio HSM integration].
	For environments that require HSM integration during adoption, see xref:adopting-the-key-manager-service-with-proteccio-hsm_hsm-integration[Adopting the {key_manager} with Proteccio HSM integration].

	Specifies the filename of the HSM server certificate as expected by the Proteccio client, for example, `10_8_60_93.CRT`.
	Specifies the filename of the HSM server certificate that is expected by the Proteccio client, for example, `10_8_60_93.CRT`.

	. Check the `OpenStackControlPlane` CR patch and the Kubernetes secrets that you created during the adoption procedure.
	. Check the `OpenStackControlPlane` custom resource (CR) patch and the Kubernetes secrets that you created during the adoption procedure.

	If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` CR includes the correct HSM settings.
	If the {key_manager_first_ref} does not detect the hardware security module (HSM) configuration after adoption, verify that the HSM configuration exists in the source environment and that the `OpenStackControlPlane` custom resource (CR) includes the correct HSM settings.

Uh oh!

Conversation

mauricioharley commented May 13, 2026

Problem

Solution

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

klgill left a comment

Choose a reason for hiding this comment

Uh oh!

jistr commented May 19, 2026

Uh oh!

openshift-ci Bot commented May 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants